package org.apache.commons.lang.builder;

import java.util.Collection;
import java.util.Comparator;

import org.apache.commons.lang.math.NumberUtils;

@SuppressWarnings({ "rawtypes", "unchecked" })
public class CompareToBuilder {

	/**
	 * Current state of the comparison as appended fields are checked.
	 */
	private int comparison;

	/**
	 * <p>
	 * Constructor for CompareToBuilder.
	 * </p>
	 * <p>
	 * Starts off assuming that the objects are equal. Multiple calls are then made to the various append methods,
	 * followed by a call to {@link #toComparison} to get the result.
	 * </p>
	 */
	public CompareToBuilder() {
		super();
		comparison = 0;
	}

	// -----------------------------------------------------------------------
	/**
	 * <p>
	 * Compares two <code>Object</code>s via reflection.
	 * </p>
	 * <p>
	 * Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control
	 * checks. This will fail under a security manager unless the appropriate permissions are set.
	 * </p>
	 * <ul>
	 * <li>Static fields will not be compared</li>
	 * <li>Transient members will be not be compared, as they are likely derived fields</li>
	 * <li>Superclass fields will be compared</li>
	 * </ul>
	 * <p>
	 * If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
	 * </p>
	 * @param lhs left-hand object
	 * @param rhs right-hand object
	 * @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater
	 *         than <code>rhs</code>
	 * @throws NullPointerException if either (but not both) parameters are <code>null</code>
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 */
	public static int reflectionCompare(Object lhs, Object rhs) {
		return reflectionCompare(lhs, rhs, false, null, null);
	}

	/**
	 * <p>
	 * Compares two <code>Object</code>s via reflection.
	 * </p>
	 * <p>
	 * Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control
	 * checks. This will fail under a security manager unless the appropriate permissions are set.
	 * </p>
	 * <ul>
	 * <li>Static fields will not be compared</li>
	 * <li>If <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores them,
	 * as they are likely derived fields.</li>
	 * <li>Superclass fields will be compared</li>
	 * </ul>
	 * <p>
	 * If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
	 * </p>
	 * @param lhs left-hand object
	 * @param rhs right-hand object
	 * @param compareTransients whether to compare transient fields
	 * @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater
	 *         than <code>rhs</code>
	 * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 */
	public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients) {
		return reflectionCompare(lhs, rhs, compareTransients, null, null);
	}

	/**
	 * <p>
	 * Compares two <code>Object</code>s via reflection.
	 * </p>
	 * <p>
	 * Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control
	 * checks. This will fail under a security manager unless the appropriate permissions are set.
	 * </p>
	 * <ul>
	 * <li>Static fields will not be compared</li>
	 * <li>If <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores them,
	 * as they are likely derived fields.</li>
	 * <li>Superclass fields will be compared</li>
	 * </ul>
	 * <p>
	 * If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
	 * </p>
	 * @param lhs left-hand object
	 * @param rhs right-hand object
	 * @param excludeFields Collection of String fields to exclude
	 * @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater
	 *         than <code>rhs</code>
	 * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 * @since 2.2
	 */
	public static int reflectionCompare(Object lhs, Object rhs, Collection /* String */excludeFields) {
		throw new UnsupportedOperationException("reflectionCompare()");
	}

	/**
	 * <p>
	 * Compares two <code>Object</code>s via reflection.
	 * </p>
	 * <p>
	 * Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control
	 * checks. This will fail under a security manager unless the appropriate permissions are set.
	 * </p>
	 * <ul>
	 * <li>Static fields will not be compared</li>
	 * <li>If <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores them,
	 * as they are likely derived fields.</li>
	 * <li>Superclass fields will be compared</li>
	 * </ul>
	 * <p>
	 * If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
	 * </p>
	 * @param lhs left-hand object
	 * @param rhs right-hand object
	 * @param excludeFields array of fields to exclude
	 * @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater
	 *         than <code>rhs</code>
	 * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 * @since 2.2
	 */
	public static int reflectionCompare(Object lhs, Object rhs, String[] excludeFields) {
		return reflectionCompare(lhs, rhs, false, null, excludeFields);
	}

	/**
	 * <p>
	 * Compares two <code>Object</code>s via reflection.
	 * </p>
	 * <p>
	 * Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control
	 * checks. This will fail under a security manager unless the appropriate permissions are set.
	 * </p>
	 * <ul>
	 * <li>Static fields will not be compared</li>
	 * <li>If the <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores
	 * them, as they are likely derived fields.</li>
	 * <li>Compares superclass fields up to and including <code>reflectUpToClass</code>. If
	 * <code>reflectUpToClass</code> is <code>null</code>, compares all superclass fields.</li>
	 * </ul>
	 * <p>
	 * If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
	 * </p>
	 * @param lhs left-hand object
	 * @param rhs right-hand object
	 * @param compareTransients whether to compare transient fields
	 * @param reflectUpToClass last superclass for which fields are compared
	 * @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater
	 *         than <code>rhs</code>
	 * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 * @since 2.0
	 */
	public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class reflectUpToClass) {
		return reflectionCompare(lhs, rhs, false, reflectUpToClass, null);
	}

	/**
	 * <p>
	 * Compares two <code>Object</code>s via reflection.
	 * </p>
	 * <p>
	 * Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control
	 * checks. This will fail under a security manager unless the appropriate permissions are set.
	 * </p>
	 * <ul>
	 * <li>Static fields will not be compared</li>
	 * <li>If the <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores
	 * them, as they are likely derived fields.</li>
	 * <li>Compares superclass fields up to and including <code>reflectUpToClass</code>. If
	 * <code>reflectUpToClass</code> is <code>null</code>, compares all superclass fields.</li>
	 * </ul>
	 * <p>
	 * If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
	 * </p>
	 * @param lhs left-hand object
	 * @param rhs right-hand object
	 * @param compareTransients whether to compare transient fields
	 * @param reflectUpToClass last superclass for which fields are compared
	 * @param excludeFields fields to exclude
	 * @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater
	 *         than <code>rhs</code>
	 * @throws NullPointerException if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 * @since 2.2
	 */
	public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class reflectUpToClass, String[] excludeFields) {
		throw new UnsupportedOperationException("reflectionCompare()");
	}

	// -----------------------------------------------------------------------
	/**
	 * <p>
	 * Appends to the <code>builder</code> the <code>compareTo(Object)</code> result of the superclass.
	 * </p>
	 * @param superCompareTo result of calling <code>super.compareTo(Object)</code>
	 * @return this - used to chain append calls
	 * @since 2.0
	 */
	public CompareToBuilder appendSuper(int superCompareTo) {
		if (comparison != 0) {
			return this;
		}
		comparison = superCompareTo;
		return this;
	}

	// -----------------------------------------------------------------------
	/**
	 * <p>
	 * Appends to the <code>builder</code> the comparison of two <code>Object</code>s.
	 * </p>
	 * <ol>
	 * <li>Check if <code>lhs == rhs</code></li>
	 * <li>Check if either <code>lhs</code> or <code>rhs</code> is <code>null</code>, a <code>null</code> object is less
	 * than a non-<code>null</code> object</li>
	 * <li>Check the object contents</li>
	 * </ol>
	 * <p>
	 * <code>lhs</code> must either be an array or implement {@link Comparable}.
	 * </p>
	 * @param lhs left-hand object
	 * @param rhs right-hand object
	 * @return this - used to chain append calls
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 */
	public CompareToBuilder append(Object lhs, Object rhs) {
		return append(lhs, rhs, null);
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the comparison of two <code>Object</code>s.
	 * </p>
	 * <ol>
	 * <li>Check if <code>lhs == rhs</code></li>
	 * <li>Check if either <code>lhs</code> or <code>rhs</code> is <code>null</code>, a <code>null</code> object is less
	 * than a non-<code>null</code> object</li>
	 * <li>Check the object contents</li>
	 * </ol>
	 * <p>
	 * If <code>lhs</code> is an array, array comparison methods will be used. Otherwise <code>comparator</code> will be
	 * used to compare the objects. If <code>comparator</code> is <code>null</code>, <code>lhs</code> must implement
	 * {@link Comparable} instead.
	 * </p>
	 * @param lhs left-hand object
	 * @param rhs right-hand object
	 * @param comparator <code>Comparator</code> used to compare the objects, <code>null</code> means treat lhs as
	 *            <code>Comparable</code>
	 * @return this - used to chain append calls
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 * @since 2.0
	 */
	public CompareToBuilder append(Object lhs, Object rhs, Comparator comparator) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.getClass().isArray()) {
			// switch on type of array, to dispatch to the correct handler
			// handles multi dimensional arrays
			// throws a ClassCastException if rhs is not the correct array type
			if (lhs instanceof long[]) {
				append((long[]) lhs, (long[]) rhs);
			} else if (lhs instanceof int[]) {
				append((int[]) lhs, (int[]) rhs);
			} else if (lhs instanceof short[]) {
				append((short[]) lhs, (short[]) rhs);
			} else if (lhs instanceof char[]) {
				append((char[]) lhs, (char[]) rhs);
			} else if (lhs instanceof byte[]) {
				append((byte[]) lhs, (byte[]) rhs);
			} else if (lhs instanceof double[]) {
				append((double[]) lhs, (double[]) rhs);
			} else if (lhs instanceof float[]) {
				append((float[]) lhs, (float[]) rhs);
			} else if (lhs instanceof boolean[]) {
				append((boolean[]) lhs, (boolean[]) rhs);
			} else {
				// not an array of primitives
				// throws a ClassCastException if rhs is not an array
				append((Object[]) lhs, (Object[]) rhs, comparator);
			}
		} else {
			// the simple case, not an array, just test the element
			if (comparator == null) {
				comparison = ((Comparable) lhs).compareTo(rhs);
			} else {
				comparison = comparator.compare(lhs, rhs);
			}
		}
		return this;
	}

	// -------------------------------------------------------------------------
	/**
	 * Appends to the <code>builder</code> the comparison of two <code>long</code>s.
	 * @param lhs left-hand value
	 * @param rhs right-hand value
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(long lhs, long rhs) {
		if (comparison != 0) {
			return this;
		}
		comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
		return this;
	}

	/**
	 * Appends to the <code>builder</code> the comparison of two <code>int</code>s.
	 * @param lhs left-hand value
	 * @param rhs right-hand value
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(int lhs, int rhs) {
		if (comparison != 0) {
			return this;
		}
		comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
		return this;
	}

	/**
	 * Appends to the <code>builder</code> the comparison of two <code>short</code>s.
	 * @param lhs left-hand value
	 * @param rhs right-hand value
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(short lhs, short rhs) {
		if (comparison != 0) {
			return this;
		}
		comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
		return this;
	}

	/**
	 * Appends to the <code>builder</code> the comparison of two <code>char</code>s.
	 * @param lhs left-hand value
	 * @param rhs right-hand value
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(char lhs, char rhs) {
		if (comparison != 0) {
			return this;
		}
		comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
		return this;
	}

	/**
	 * Appends to the <code>builder</code> the comparison of two <code>byte</code>s.
	 * @param lhs left-hand value
	 * @param rhs right-hand value
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(byte lhs, byte rhs) {
		if (comparison != 0) {
			return this;
		}
		comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the comparison of two <code>double</code>s.
	 * </p>
	 * <p>
	 * This handles NaNs, Infinities, and <code>-0.0</code>.
	 * </p>
	 * <p>
	 * It is compatible with the hash code generated by <code>HashCodeBuilder</code>.
	 * </p>
	 * @param lhs left-hand value
	 * @param rhs right-hand value
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(double lhs, double rhs) {
		if (comparison != 0) {
			return this;
		}
		comparison = NumberUtils.compare(lhs, rhs);
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the comparison of two <code>float</code>s.
	 * </p>
	 * <p>
	 * This handles NaNs, Infinities, and <code>-0.0</code>.
	 * </p>
	 * <p>
	 * It is compatible with the hash code generated by <code>HashCodeBuilder</code>.
	 * </p>
	 * @param lhs left-hand value
	 * @param rhs right-hand value
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(float lhs, float rhs) {
		if (comparison != 0) {
			return this;
		}
		comparison = NumberUtils.compare(lhs, rhs);
		return this;
	}

	/**
	 * Appends to the <code>builder</code> the comparison of two <code>booleans</code>s.
	 * @param lhs left-hand value
	 * @param rhs right-hand value
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(boolean lhs, boolean rhs) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == false) {
			comparison = -1;
		} else {
			comparison = +1;
		}
		return this;
	}

	// -----------------------------------------------------------------------
	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>Object</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a short length array is less than a long length array</li>
	 * <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li>
	 * </ol>
	 * <p>
	 * This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.
	 * </p>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @return this - used to chain append calls
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 */
	public CompareToBuilder append(Object[] lhs, Object[] rhs) {
		return append(lhs, rhs, null);
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>Object</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a short length array is less than a long length array</li>
	 * <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li>
	 * </ol>
	 * <p>
	 * This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.
	 * </p>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @param comparator <code>Comparator</code> to use to compare the array elements, <code>null</code> means to treat
	 *            <code>lhs</code> elements as <code>Comparable</code>.
	 * @return this - used to chain append calls
	 * @throws ClassCastException if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
	 * @since 2.0
	 */
	public CompareToBuilder append(Object[] lhs, Object[] rhs, Comparator comparator) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.length != rhs.length) {
			comparison = (lhs.length < rhs.length) ? -1 : +1;
			return this;
		}
		for (int i = 0; i < lhs.length && comparison == 0; i++) {
			append(lhs[i], rhs[i], comparator);
		}
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>long</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a shorter length array is less than a longer length array</li>
	 * <li>Check array contents element by element using {@link #append(long, long)}</li>
	 * </ol>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(long[] lhs, long[] rhs) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.length != rhs.length) {
			comparison = (lhs.length < rhs.length) ? -1 : +1;
			return this;
		}
		for (int i = 0; i < lhs.length && comparison == 0; i++) {
			append(lhs[i], rhs[i]);
		}
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>int</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a shorter length array is less than a longer length array</li>
	 * <li>Check array contents element by element using {@link #append(int, int)}</li>
	 * </ol>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(int[] lhs, int[] rhs) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.length != rhs.length) {
			comparison = (lhs.length < rhs.length) ? -1 : +1;
			return this;
		}
		for (int i = 0; i < lhs.length && comparison == 0; i++) {
			append(lhs[i], rhs[i]);
		}
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>short</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a shorter length array is less than a longer length array</li>
	 * <li>Check array contents element by element using {@link #append(short, short)}</li>
	 * </ol>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(short[] lhs, short[] rhs) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.length != rhs.length) {
			comparison = (lhs.length < rhs.length) ? -1 : +1;
			return this;
		}
		for (int i = 0; i < lhs.length && comparison == 0; i++) {
			append(lhs[i], rhs[i]);
		}
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>char</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a shorter length array is less than a longer length array</li>
	 * <li>Check array contents element by element using {@link #append(char, char)}</li>
	 * </ol>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(char[] lhs, char[] rhs) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.length != rhs.length) {
			comparison = (lhs.length < rhs.length) ? -1 : +1;
			return this;
		}
		for (int i = 0; i < lhs.length && comparison == 0; i++) {
			append(lhs[i], rhs[i]);
		}
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>byte</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a shorter length array is less than a longer length array</li>
	 * <li>Check array contents element by element using {@link #append(byte, byte)}</li>
	 * </ol>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(byte[] lhs, byte[] rhs) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.length != rhs.length) {
			comparison = (lhs.length < rhs.length) ? -1 : +1;
			return this;
		}
		for (int i = 0; i < lhs.length && comparison == 0; i++) {
			append(lhs[i], rhs[i]);
		}
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>double</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a shorter length array is less than a longer length array</li>
	 * <li>Check array contents element by element using {@link #append(double, double)}</li>
	 * </ol>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(double[] lhs, double[] rhs) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.length != rhs.length) {
			comparison = (lhs.length < rhs.length) ? -1 : +1;
			return this;
		}
		for (int i = 0; i < lhs.length && comparison == 0; i++) {
			append(lhs[i], rhs[i]);
		}
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>float</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a shorter length array is less than a longer length array</li>
	 * <li>Check array contents element by element using {@link #append(float, float)}</li>
	 * </ol>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(float[] lhs, float[] rhs) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.length != rhs.length) {
			comparison = (lhs.length < rhs.length) ? -1 : +1;
			return this;
		}
		for (int i = 0; i < lhs.length && comparison == 0; i++) {
			append(lhs[i], rhs[i]);
		}
		return this;
	}

	/**
	 * <p>
	 * Appends to the <code>builder</code> the deep comparison of two <code>boolean</code> arrays.
	 * </p>
	 * <ol>
	 * <li>Check if arrays are the same using <code>==</code></li>
	 * <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
	 * <li>Check array length, a shorter length array is less than a longer length array</li>
	 * <li>Check array contents element by element using {@link #append(boolean, boolean)}</li>
	 * </ol>
	 * @param lhs left-hand array
	 * @param rhs right-hand array
	 * @return this - used to chain append calls
	 */
	public CompareToBuilder append(boolean[] lhs, boolean[] rhs) {
		if (comparison != 0) {
			return this;
		}
		if (lhs == rhs) {
			return this;
		}
		if (lhs == null) {
			comparison = -1;
			return this;
		}
		if (rhs == null) {
			comparison = +1;
			return this;
		}
		if (lhs.length != rhs.length) {
			comparison = (lhs.length < rhs.length) ? -1 : +1;
			return this;
		}
		for (int i = 0; i < lhs.length && comparison == 0; i++) {
			append(lhs[i], rhs[i]);
		}
		return this;
	}

	// -----------------------------------------------------------------------
	/**
	 * Returns a negative integer, a positive integer, or zero as the <code>builder</code> has judged the "left-hand"
	 * side as less than, greater than, or equal to the "right-hand" side.
	 * @return final comparison result
	 */
	public int toComparison() {
		return comparison;
	}

}
